<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>7.6. The Dispatcher</title>
<link rel="stylesheet" href="dbstyle.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
<link rel="start" href="index.html" title="Programmer's Reference Guide">
<link rel="up" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="prev" href="zend.controller.router.html" title="7.5. The Standard Router: Zend_Controller_Router_Rewrite">
<link rel="next" href="zend.controller.action.html" title="7.7. Action Controllers">
<link rel="chapter" href="introduction.html" title="Chapter 1. Introduction to Zend Framework">
<link rel="chapter" href="zend.acl.html" title="Chapter 2. Zend_Acl">
<link rel="chapter" href="zend.auth.html" title="Chapter 3. Zend_Auth">
<link rel="chapter" href="zend.cache.html" title="Chapter 4. Zend_Cache">
<link rel="chapter" href="zend.config.html" title="Chapter 5. Zend_Config">
<link rel="chapter" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="chapter" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="chapter" href="zend.currency.html" title="Chapter 8. Zend_Currency">
<link rel="chapter" href="zend.date.html" title="Chapter 9. Zend_Date">
<link rel="chapter" href="zend.db.html" title="Chapter 10. Zend_Db">
<link rel="chapter" href="zend.debug.html" title="Chapter 11. Zend_Debug">
<link rel="chapter" href="zend.dojo.html" title="Chapter 12. Zend_Dojo">
<link rel="chapter" href="zend.dom.html" title="Chapter 13. Zend_Dom">
<link rel="chapter" href="zend.exception.html" title="Chapter 14. Zend_Exception">
<link rel="chapter" href="zend.feed.html" title="Chapter 15. Zend_Feed">
<link rel="chapter" href="zend.filter.html" title="Chapter 16. Zend_Filter">
<link rel="chapter" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="chapter" href="zend.gdata.html" title="Chapter 18. Zend_Gdata">
<link rel="chapter" href="zend.http.html" title="Chapter 19. Zend_Http">
<link rel="chapter" href="zend.infocard.html" title="Chapter 20. Zend_InfoCard">
<link rel="chapter" href="zend.json.html" title="Chapter 21. Zend_Json">
<link rel="chapter" href="zend.layout.html" title="Chapter 22. Zend_Layout">
<link rel="chapter" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="chapter" href="zend.loader.html" title="Chapter 24. Zend_Loader">
<link rel="chapter" href="zend.locale.html" title="Chapter 25. Zend_Locale">
<link rel="chapter" href="zend.log.html" title="Chapter 26. Zend_Log">
<link rel="chapter" href="zend.mail.html" title="Chapter 27. Zend_Mail">
<link rel="chapter" href="zend.measure.html" title="Chapter 28. Zend_Measure">
<link rel="chapter" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="chapter" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="zend.openid.html" title="Chapter 31. Zend_OpenId">
<link rel="chapter" href="zend.paginator.html" title="Chapter 32. Zend_Paginator">
<link rel="chapter" href="zend.pdf.html" title="Chapter 33. Zend_Pdf">
<link rel="chapter" href="zend.registry.html" title="Chapter 34. Zend_Registry">
<link rel="chapter" href="zend.rest.html" title="Chapter 35. Zend_Rest">
<link rel="chapter" href="zend.search.lucene.html" title="Chapter 36. Zend_Search_Lucene">
<link rel="chapter" href="zend.server.html" title="Chapter 37. Zend_Server">
<link rel="chapter" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="chapter" href="zend.session.html" title="Chapter 39. Zend_Session">
<link rel="chapter" href="zend.soap.html" title="Chapter 40. Zend_Soap">
<link rel="chapter" href="zend.test.html" title="Chapter 41. Zend_Test">
<link rel="chapter" href="zend.text.html" title="Chapter 42. Zend_Text">
<link rel="chapter" href="zend.timesync.html" title="Chapter 43. Zend_TimeSync">
<link rel="chapter" href="zend.translate.html" title="Chapter 44. Zend_Translate">
<link rel="chapter" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="chapter" href="zend.validate.html" title="Chapter 46. Zend_Validate">
<link rel="chapter" href="zend.version.html" title="Chapter 47. Zend_Version">
<link rel="chapter" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="chapter" href="zend.xmlrpc.html" title="Chapter 49. Zend_XmlRpc">
<link rel="appendix" href="requirements.html" title="Appendix A. Zend Framework Requirements">
<link rel="appendix" href="coding-standard.html" title="Appendix B. Zend Framework Coding Standard for PHP">
<link rel="appendix" href="copyrights.html" title="Appendix C. Copyright Information">
<link rel="index" href="the.index.html" title="Index">
<link rel="subsection" href="zend.controller.dispatcher.html#zend.controller.dispatcher.overview" title="7.6.1. Overview">
<link rel="subsection" href="zend.controller.dispatcher.html#zend.controller.dispatcher.subclassing" title="7.6.2. Subclassing the Dispatcher">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader"><table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">7.6. The Dispatcher</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="zend.controller.router.html">Prev</a> </td>
<th width="60%" align="center">Chapter 7. Zend_Controller</th>
<td width="20%" align="right"> <a accesskey="n" href="zend.controller.action.html">Next</a>
</td>
</tr>
</table></div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="zend.controller.dispatcher"></a>7.6. The Dispatcher</h2></div></div></div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.controller.dispatcher.overview"></a>7.6.1. Overview</h3></div></div></div>
<p>
            Dispatching is the process of taking the request object,
            <code class="code">Zend_Controller_Request_Abstract</code>, extracting the module
            name, controller name, action name, and optional parameters
            contained in it, and then instantiating a controller and calling an
            action of that controller. If any of the module, controller, or
            action are not found, it will use default values for them.
            <code class="code">Zend_Controller_Dispatcher_Standard</code> specifies
            <code class="code">index</code> for each of the controller and action defaults
            and <code class="code">default</code> for the module default value, but allows
            the developer to change the default values for each using the
            <code class="code">setDefaultController()</code>,
            <code class="code">setDefaultAction()</code>, and <code class="code">setDefaultModule()</code>
            methods, respectively.
        </p>
<div class="note"><table border="0" summary="Note: Default Module">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Default Module</th>
</tr>
<tr><td align="left" valign="top">
<p>
                When creating modular applications, you may find that you want
                your default module namespaced as well (the default
                configuration is that the default module is
                <span class="emphasis"><em>not</em></span> namespaced). As of 1.5.0, you can now
                do so by specifying the <code class="code">prefixDefaultModule</code> as true
                in either the front controller or your dispatcher:
            </p>
<pre class="programlisting">&lt;?php 
// In your front controller:
$front-&gt;setParam('prefixDefaultModule', true);

// In your dispatcher:
$dispatcher-&gt;setParam('prefixDefaultModule', true);
?&gt;</pre>
<p>
                This allows you to re-purpose an existing module to be the
                default module for an application.
            </p>
</td></tr>
</table></div>
<p>
            Dispatching happens in a loop in the front controller. Before
            dispatching occurs, the front controller routes the request to find
            user specified values for the module, controller, action, and optional
            parameters. It then enters a dispatch loop, dispatching the request.
        </p>
<p>
            At the beginning of each iteration, it sets a flag in the request
            object indicating that the action has been dispatched. If an action
            or pre/postDispatch plugin resets that flag, the dispatch loop will
            continue and attempt to dispatch the new request. By changing the
            controller and/or action in the request and resetting the dispatched
            flag, the developer may define a chain of requests to perform.
        </p>
<p>
            The action controller method that controls such dispatching is
            <code class="code">_forward()</code>; call this method from any of the
            pre/postDispatch() or action methods, providing an action, controller,
            module, and optionally any additional parameters you may wish to
            send to the new action:
        </p>
<pre class="programlisting">&lt;?php
public function fooAction()
{
    // forward to another action in the current controller and module:
    $this-&gt;_forward('bar', null, null, array('baz' =&gt; 'bogus'));
}

public function barAction()
{
    // forward to an action in another controller, FooController::bazAction(),
    // in the current module:
    $this-&gt;_forward('baz', 'foo', null, array('baz' =&gt; 'bogus'));
}

public function bazAction()
{
    // forward to an action in another controller in another module,
    // Foo_BarController::bazAction():
    $this-&gt;_forward('baz', 'bar', 'foo', array('baz' =&gt; 'bogus'));
}
        </pre>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.controller.dispatcher.subclassing"></a>7.6.2. Subclassing the Dispatcher</h3></div></div></div>
<p>
            <code class="code">Zend_Controller_Front</code> will first call the router to
            determine the first action in the request. It then enters a dispatch
            loop, which calls on the dispatcher to dispatch the action.
        </p>
<p>
            The dispatcher needs a variety of data in order to do its work - it
            needs to know how to format controller and action names, where to
            look for controller class files, whether or not a provided module
            name is valid, and an API for determining if a given request is even
            dispatchable based on the other information available.
        </p>
<p>
            <code class="code">Zend_Controller_Dispatcher_Interface</code> defines the
            following methods as required for any dispatcher implementation:
        </p>
<pre class="programlisting">
interface Zend_Controller_Dispatcher_Interface
{
    /**
     * Format a string into a controller class name.
     *
     * @param string $unformatted
     * @return string
     */
    public function formatControllerName($unformatted);

    /**
     * Format a string into an action method name.
     *
     * @param string $unformatted
     * @return string
     */
    public function formatActionName($unformatted);

    /**
     * Determine if a request is dispatchable
     *
     * @param  Zend_Controller_Request_Abstract $request
     * @return boolean
     */
    public function isDispatchable(Zend_Controller_Request_Abstract $request);

    /**
     * Set a user parameter (via front controller, or for local use)
     *
     * @param string $name
     * @param mixed $value
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setParam($name, $value);

    /**
     * Set an array of user parameters
     *
     * @param array $params
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setParams(array $params);

    /**
     * Retrieve a single user parameter
     *
     * @param string $name
     * @return mixed
     */
    public function getParam($name);

    /**
     * Retrieve all user parameters
     *
     * @return array
     */
    public function getParams();

    /**
     * Clear the user parameter stack, or a single user parameter
     *
     * @param null|string|array single key or array of keys for params to clear
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function clearParams($name = null);

    /**
     * Set the response object to use, if any
     *
     * @param Zend_Controller_Response_Abstract|null $response
     * @return void
     */
    public function setResponse(Zend_Controller_Response_Abstract $response = null);

    /**
     * Retrieve the response object, if any
     *
     * @return Zend_Controller_Response_Abstract|null
     */
    public function getResponse();

    /**
     * Add a controller directory to the controller directory stack
     *
     * @param string $path
     * @param string $args
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function addControllerDirectory($path, $args = null);

    /**
     * Set the directory (or directories) where controller files are stored
     *
     * @param string|array $dir
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setControllerDirectory($path);

    /**
     * Return the currently set directory(ies) for controller file lookup
     *
     * @return array
     */
    public function getControllerDirectory();

    /**
     * Dispatch a request to a (module/)controller/action.
     *
     * @param  Zend_Controller_Request_Abstract $request
     * @param  Zend_Controller_Response_Abstract $response
     * @return Zend_Controller_Request_Abstract|boolean
     */
    public function dispatch(Zend_Controller_Request_Abstract $request, Zend_Controller_Response_Abstract $response);

    /**
     * Whether or not a given module is valid
     *
     * @param string $module
     * @return boolean
     */
    public function isValidModule($module);
}
        </pre>
<p>
            In most cases, however, you should simply extend the abstract class
            <code class="code">Zend_Controller_Dispatcher_Abstract</code>, in which each of
            these have already been defined, or
            <code class="code">Zend_Controller_Dispatcher_Standard</code> to modify
            functionality of the standard dispatcher.
        </p>
<p>
            Possible reasons to subclass the dispatcher include a desire to
            use a different class or method naming schema in your action
            controllers, or a desire to use a different dispatching paradigm
            such as dispatching to action files under controller directories
            (instead of dispatching to class methods).
        </p>
</div>
</div>
<div class="navfooter"><table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="zend.controller.router.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="zend.controller.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="zend.controller.action.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">7.5. The Standard Router: Zend_Controller_Router_Rewrite </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 7.7. Action Controllers</td>
</tr>
</table></div>
<div class="revinfo"></div>
</body>
</html>
